ИИ-агент — Настройка и интеграция

Версия: 1.0
Дата: 19.04.2026
Статус: Утверждён

Руководство по настройке ИИ-агента (Claude Code) для автономной работы внутри системы документооборота с DocMap MCP.

Жёсткие правила поведения агента: cms-system/reference/ИИ-агент — Свод законов.md

---

Архитектура

Агент управляется четырьмя системами одновременно:

┌─────────────────────────────────────────────────────┐
│  ПРОМТ — контекст старта, slug проекта, стиль       │
│  (короткий, детали делегированы в свод)             │
├─────────────────────────────────────────────────────┤
│  ХУК — срабатывает на каждое действие               │
│  блокировки + напоминания + ссылка на свод          │
├─────────────────────────────────────────────────────┤
│  СВОД ЗАКОНОВ — полный алгоритм и правила           │
│  документ в системе, агент читает по ссылке         │
├─────────────────────────────────────────────────────┤
│  MEMORY — контекст проекта, предпочтения,           │
│  накапливается автоматически между сессиями         │
└─────────────────────────────────────────────────────┘

Принцип: промт задаёт личность, хук держит дисциплину, свод даёт алгоритм, память сохраняет контекст. Ни одна система не дублирует другую.

---

1. Промт

Промт короткий — детали в своде законов. Задача промта: кто агент, в каком проекте, уровень автономии.

Шаблон промта

Ты — ИИ-агент системы документооборота на базе Docusaurus + Decap CMS + DocMap MCP.

ПРОЕКТ: <название проекта>
SLUG: <project-slug>
РЕПОЗИТОРИЙ: <путь к репозиторию>

РЕЖИМ РАБОТЫ: автономный. Выполняешь задачи полностью самостоятельно включая git commit.
Если неясно — консультируешься с пользователем до начала действий, не в середине.

СВОД ЗАКОНОВ (прочитать перед началом работы):
docs/<cms-system>/reference/ИИ-агент — Свод законов.md

ИНСТРУМЕНТЫ:
- DocMap MCP: docs_index, docs_search, docs_get_section, docs_patch_section, docs_create_section, docs_create_file
- tools/: build_project_index.sh, build_index.sh, sync_assets.sh, add_user.sh, export_project.sh
- git: add <файлы>, commit, status, diff

ПРИНЦИПЫ (кратко):
- Код первичен. Документация — ориентир.
- Сначала читать (DocMap + файлы), потом писать.
- Slug проекта сверять перед каждой правкой.
- Документацию обновлять в рамках той же задачи что и код.
- Чужие проекты — читать можно, писать — только с явного разрешения.

Как адаптировать под проект

Заменить:

• <название проекта> — человекочитаемое название из _project_.json → label
• <project-slug> — имя папки в docs/
• <путь к репозиторию> — абсолютный путь к корню репозитория

Если агент работает со всеми проектами системы одновременно — убрать строки ПРОЕКТ и SLUG, добавить:

ПРОЕКТЫ: все проекты в docs/ — работать только с тем, который явно указан в задаче.

---

2. Memory

Memory накапливается автоматически между сессиями. Хранится в ~/.claude/projects/<hash>/memory/.

Что агент должен запоминать

Тип project — факты о проекте:

---
type: project
name: <slug> — структура и состояние
description: Текущее состояние проекта, ключевые решения
---

Slug: <project-slug>
Путь: docs/<project-slug>/
Label: <название из _project_.json>

Активные разделы: overview, reference (operations и development пустые)
Последние изменения: <что менялось>
Незакрытые задачи: <если есть>

Тип feedback — предпочтения пользователя:

---
type: feedback
name: предпочтения работы с документацией
description: Как пользователь хочет чтобы агент вёл документацию
---

Правило: <что делать или не делать>
Почему: <причина>
Как применять: <когда срабатывает>

Тип user — профиль пользователя:

---
type: user
name: профиль владельца системы
description: Роль, уровень экспертизы, предпочтения взаимодействия
---

Роль: <кто пользователь>
Экспертиза: <что знает хорошо>
Предпочтения: <краткие ответы / подробные объяснения / и т.д.>

Что НЕ сохранять в memory

• Пути к файлам и структуру папок — читать из репозитория напрямую
• Содержимое документов — читать через DocMap
• Историю git — читать через git log
• Временные состояния текущей задачи — это для TaskCreate, не memory

---

3. Хук

Единый хук — расширение существующего PreToolUse/PostToolUse. Не плодить отдельные хуки.

PreToolUse — блокировки и напоминания

Хук срабатывает перед каждым Edit/Write. Выполняет три проверки:

Проверка 1: защита системных файлов Блокирует прямое редактирование файлов которые должны меняться только через скрипты:

• index.md любого проекта → только через build_project_index.sh
• CREDENTIALS_HASH в static/admin/index.html → только через add_user.sh --admin
• url/title в docusaurus.config.ts → только через cms-config.json

Проверка 2: защита чужих проектов Если файл в docs/<slug>/ и этот slug не совпадает с текущим рабочим проектом из памяти — предупреждение с требованием подтверждения.

Проверка 3: напоминание о своде Если marker-файл не выставлен — показать напоминание со ссылкой на свод законов и инструменты DocMap. Агент выставляет marker после того как прочитал DocMap и готов писать.

Конфигурация хука

Хук уже подключён в проектном файле .claude/settings.json (в корне репозитория). Этот файл автоматически подхватывается Claude Code при открытии проекта — ничего дополнительно настраивать не нужно.

Где лежит:

cms-docs/
└── .claude/
    ├── settings.json        ← хук (подключается автоматически для этого проекта)
    └── settings.local.json  ← локальные разрешения (в git не коммитится)

Проверить что хук активен — открыть Claude Code в папке проекта и попробовать отредактировать любой файл в docs/. Должно появиться сообщение хука.

Если нужно подключить глобально (для всех проектов) — скопировать блок hooks из .claude/settings.json в ~/.claude/settings.json. Путь к скрипту при этом должен быть абсолютным:

/home/alex/sites/cms-docs/tools/agent_hook.sh

Текущая конфигурация .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "timeout": 10,
            "command": "f=$(jq -r '.tool_input.file_path // empty' 2>/dev/null); [ -z \"$f\" ] && exit 0; bash /home/alex/sites/cms-docs/tools/agent_hook.sh pre \"$f\""
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "timeout": 10,
            "command": "f=$(jq -r '.tool_input.file_path // empty' 2>/dev/null); [ -z \"$f\" ] && exit 0; bash /home/alex/sites/cms-docs/tools/agent_hook.sh post \"$f\""
          }
        ]
      }
    ]
  }
}

Важно: $(jq ...) нельзя встраивать напрямую в строку команды — он выполнится при старте Claude, а не при срабатывании хука. Правильный паттерн: сначала f=$(jq ...) в shell-команде, затем передать $f в скрипт.

### Скрипт хука `tools/agent_hook.sh`

Логика вынесена в отдельный скрипт — легко обновлять без правки `settings.json`.

```bash
#!/usr/bin/env bash
# Хук ИИ-агента для системы документооборота
# Использование: agent_hook.sh pre|post <file_path>

MODE="$1"
FILE="$2"
REPO="$(git -C "$(dirname "$(realpath "$0")")" rev-parse --show-toplevel)"
LAWS="$REPO/docs/cms-system/reference/ИИ-агент — Свод законов.md"
MARKER="/tmp/docmap_ok_$(echo "$FILE" | md5sum | cut -c1-8)"

# Файлы .claude/* — не требуют проверки
echo "$FILE" | grep -q '\.claude/' && exit 0
[ -z "$FILE" ] && exit 0

msg() { python3 -c "import json,sys; print(json.dumps({'hookSpecificOutput':{'hookEventName':'PreToolUse','additionalContext':sys.argv[1]}}))" "$1" 2>/dev/null; }

if [ "$MODE" = "pre" ]; then

  # --- Защита index.md от ручного редактирования ---
  if echo "$FILE" | grep -qE '/docs/[^/]+/index\.md$'; then
    SLUG=$(echo "$FILE" | sed 's|.*/docs/\([^/]*\)/index\.md|\1|')
    msg "СТОП. index.md нельзя редактировать вручную.
Файл: $FILE

Обновить через скрипт:
  tools/build_project_index.sh $SLUG

Свод законов: $LAWS (правило 10)"
    exit 2
  fi

  # --- Защита системных файлов ---
  if echo "$FILE" | grep -qE 'static/admin/index\.html|docusaurus\.config\.ts'; then
    if echo "$FILE" | grep -q 'index\.html'; then
      msg "СТОП. static/admin/index.html — только через скрипт.
Смена пароля:  tools/add_user.sh --admin <пароль>
Смена логина:  сначала cms-config.json → admin.username, затем add_user.sh --admin

Свод законов: $LAWS (правило 15)"
    else
      msg "СТОП. docusaurus.config.ts — url и title только через cms-config.json → site.*
После изменения конфига пересобрать: npm run build

Свод законов: $LAWS (правило 14)"
    fi
    exit 2
  fi

  # --- Защита static/ от прямой записи медиа ---
  if echo "$FILE" | grep -qE '/static/.+\.(png|jpg|jpeg|svg|gif|pdf|webp)$'; then
    SLUG=$(echo "$FILE" | sed 's|.*/static/\([^/]*\)/.*|\1|')
    msg "СТОП. Медиафайлы нельзя класть в static/ напрямую.
Положить в: docs/$SLUG/assets/$(basename "$FILE")
Затем синхронизировать: tools/sync_assets.sh $SLUG

Свод законов: $LAWS (правило 9)"
    exit 2
  fi

  # --- Напоминание о своде если marker не выставлен ---
  [ -f "$MARKER" ] && exit 0

  msg "СТОП. Перед записью — проверь документацию и сверь проект.

КОД ПЕРВИЧЕН. Документация — ориентир, не источник истины.

АЛГОРИТМ (порядок строгий):
1. docs_index / docs_search / docs_get_section — ориентация
2. Read/Grep реальных файлов — сверка с кодом
3. Сверка slug: папка docs/<slug>/ совпадает с задачей?
4. Выполнить задачу
5. Обновить документацию (в рамках той же задачи)
6. git add <файлы> (не -A) → git commit

ИНСТРУМЕНТЫ DocMap:
  docs_index()               — список документов проекта
  docs_search(query)         — поиск по теме
  docs_get_section(id)       — читать секцию
  docs_patch_section(id, body) — обновить секцию
  docs_create_section(...)   — добавить секцию
  docs_create_file(...)      — создать документ

СВОД ЗАКОНОВ (прочитать если неясно):
  $LAWS

Когда готов писать:
  touch $MARKER"
  exit 2

elif [ "$MODE" = "post" ]; then

  rm -f "$MARKER"

  # Напоминание после правки кода — обновить документацию
  echo "$FILE" | grep -qiE '\.(md)$' && exit 0

  msg "КОД ИЗМЕНЁН.

Обязательно в рамках этой же задачи:
1. docs_search(тема) — найти связанные секции
2. docs_patch_section / docs_create_section — обновить
3. Если новый файл в проекте: tools/build_project_index.sh <slug>
4. Затем git add <файлы> → git commit

Свод законов: $LAWS (правила 26–31)"

fi

---

4. Пример полного рабочего цикла

Задача: добавить новый документ в проект

Пользователь: "Создай документ по API авторизации в проекте vitiana-api-platform"

Агент:
1. docs_index(project: "cms-system") → найти свод законов, убедиться в структуре
2. Grep: ls docs/vitiana-api-platform/ → проверить что проект существует
3. Read: docs/vitiana-api-platform/_project_.json → убедиться в slug и label
4. docs_search("авторизация API") → есть ли уже что-то по теме
5. Определить раздел: API-контракт → reference/
6. Создать файл: docs/vitiana-api-platform/reference/api-auth.md
7. tools/build_project_index.sh vitiana-api-platform
8. docs_create_section или docs_patch_section — обновить DocMap
9. git add docs/vitiana-api-platform/reference/api-auth.md
       docs/vitiana-api-platform/index.md
10. git commit -m "docs(vitiana-api-platform): добавлена документация API авторизации"

Задача: изменить существующий документ

Пользователь: "Обнови схему БД в reference проекта vitiana-api-platform"

Агент:
1. docs_search("схема БД") → найти секцию
2. docs_get_section(id) → прочитать текущее содержимое
3. Grep реального кода/схемы → убедиться что документ соответствует реальности
4. Edit файла с изменениями (touch marker перед записью)
5. docs_patch_section(id, new_body) → обновить DocMap
6. git add <файл> → git commit

Задача: добавить медиафайл

Пользователь: "Добавь диаграмму архитектуры в проект vitiana-api-platform"

Агент:
1. Получить файл диаграммы
2. Положить в: docs/vitiana-api-platform/assets/architecture.jpg
3. tools/sync_assets.sh vitiana-api-platform
4. tools/build_project_index.sh vitiana-api-platform (обновит таблицу медиафайлов)
5. Вставить в нужный документ: ![Архитектура](/vitiana-api-platform/architecture.jpg)
6. git add docs/vitiana-api-platform/assets/architecture.jpg
       docs/vitiana-api-platform/index.md
       docs/vitiana-api-platform/<документ>.md
7. git commit

---

5. Сверка проекта — детальный алгоритм

Выполнять перед каждой первой правкой в сессии и при смене контекста:

# 1. Slug из задачи или памяти
SLUG="vitiana-api-platform"

# 2. Папка существует?
ls docs/$SLUG/

# 3. _project_.json существует и читаем?
cat docs/$SLUG/_project_.json

# 4. label совпадает с задачей?
python3 -c "import json; print(json.load(open('docs/$SLUG/_project_.json'))['label'])"

# 5. Если всё совпадает — можно работать
# Если нет — стоп, уточнить у пользователя

---

6. Работа с несколькими проектами в одной системе

Когда в docs/ несколько проектов:

• Читать можно любой проект — для контекста, сравнения, навигации
• Писать только в тот проект, который явно указан в текущей задаче
• Переход к другому проекту — новая явная инструкция от пользователя, не додумывать
• При неясности — спросить: "Вы имеете в виду проект <slug>?"

Если задача касается общесистемных файлов (cms-config.json, tools/, docusaurus.config.ts) — это не принадлежит ни одному проекту, действовать осторожно, уточнить при сомнении.

---

7. Структура папок — шпаргалка для агента

<repo>/
├── cms-config.json          ← глобальные настройки, менять только через скрипты
├── tools/                   ← скрипты, не менять без явной задачи
├── docs/
│   ├── index.md             ← генерирует build_index.sh, не редактировать
│   ├── <slug>/
│   │   ├── _project_.json   ← маркер проекта, менять осторожно
│   │   ├── index.md         ← генерирует build_project_index.sh, не редактировать
│   │   ├── assets/          ← единственное место для медиафайлов
│   │   ├── overview/        ← зачем проект, архитектура, контекст
│   │   ├── reference/       ← спецификации, схемы, API, контракты
│   │   ├── operations/      ← запуск, деплой, обслуживание
│   │   └── development/     ← роадмап, ADR, история решений
├── static/
│   └── <slug>/              ← производная от assets/, не редактировать вручную
└── static/admin/
    └── index.html           ← менять только через add_user.sh --admin

Куда класть новый документ:

Тема документа	Раздел
Концепция, зачем нужно, общая картина, ADR-обзор	overview/
API, схема БД, контракты, форматы, конфиги	reference/
Запуск, деплой, мониторинг, runbook, чиним	operations/
Роадмап, решения (ADR), планы, changelog	development/
Картинки, диаграммы, PDF	assets/

При сомнении — спросить пользователя.

---

8. Инструменты DocMap — справочник

Инструмент	Когда использовать
docs_index(project)	Старт работы — что вообще есть в проекте
docs_search(query)	Найти секцию по теме перед правкой
docs_get_section(id)	Прочитать конкретную секцию перед обновлением
docs_patch_section(id, body)	Обновить тело существующей секции
docs_create_section(file, level, title, body)	Добавить новую секцию в существующий файл
docs_create_file(file, content)	Создать новый MD-файл
docs_delete_section(id)	Удалить секцию (осторожно, подтвердить)
docs_links(id)	Граф ссылок — что ссылается на секцию
docs_lint()	Найти битые ссылки после реструктуризации

Порядок использования перед правкой:

docs_index → docs_search → docs_get_section → [читать реальный код] → писать

После правки кода:

docs_search → docs_get_section → docs_patch_section

---

9. Конфигурация DocMap MCP

Расположение файлов

Файл	Путь	Назначение
Бинарник	~/docmap-mcp	Исполняемый файл сервера
Конфиг	~/docmap/docmap.toml	Список проектов и путей
Systemd unit	~/.config/systemd/user/docmap.service	Автозапуск при старте WSL
MCP подключение	<repo>/.mcp.json	Подключение к Claude Code

Проекты в конфиге

[projects.cms-docs]
root = "/home/alex/sites/cms-docs/docs/cms-system"

[projects.vitiana-api-platform]
root = "/home/alex/sites/cms-docs/docs/vitiana-api-platform"

[projects.home-to-go-api]
root = "/mnt/d/SITES/home.to.go.api"

Управление службой

# Статус
systemctl --user status docmap

# Перезапустить (после правки docmap.toml)
systemctl --user restart docmap

# Логи
journalctl --user -u docmap -f

# Включить/выключить автозапуск
systemctl --user enable docmap
systemctl --user disable docmap

Подключение к Claude Code

В .mcp.json репозитория:

"docmap-mcp": {
  "command": "/home/alex/docmap-mcp",
  "args": ["--config", "/home/alex/docmap/docmap.toml", "stdio"]
}

После изменения docmap.toml — перезапустить службу и перезапустить сессию Claude Code.